Release notes

This page contains release notes that apply to all APIs.

2022r7

Standard JWT tokens for REST API services

It was already possible to authenticate users for a REST API using JWT. Previously, however, the implementation in WHATS'ON did not completely follow the JWT standard.

From this version, the tokens are generated according to the standard.

The JWTs are still used by setting the Authentication method on a service to User-based JWT, which now triggers the new implementation. When the correct credentials of the API user are sent using the login call of the API, the access token is returned in the response.

{
    "statusCode": "200",
    "message": "Authentication successful",
    "token": "0123456",
    "service": "BAPI"
}

When this token is decoded, it now contains the following header and claims:

  • alg or algorithm: the algorithm used to sign or encrypt the JWT. For WHATS'ON, this is always HS256.

  • typ or type: the type of the token, which should always be JWT.

  • jti or JWT ID: a generated UUID used for identification. It can be used to find the token in the issued tokens list. (RN-5008)

  • sub or subject: the name of the user for which the token was issued

  • iat or issued at: the timestamp of when the token was issued in INTDATE format.

  • exp or expiration time: the timestamp of when the token will expire in INTDATE format. This is determined by the Access token validity period (seconds) property on the service or when issuing the token (RN-5008).

  • aud or audience: the user code of the Allowed API endpoints on the user account for which the token was issued.

When the token is combined with the JWT secret of WHATS'ON, it is possible to verify the signature.

When the JWT is not accepted, a 403 response is returned:

{
    "statusCode": "403",
    "message": "The account being accessed does not have sufficient permissions 
               to execute this operation. [Additional info]",
    "timestamp": "2022-08-19T12:27:48Z"
}

The additional info in the response indicates the cause:

  • Invalid header: a different alg from HS256 or typ from JWT.

  • Invalid signature:

    • no jti or jti that does not match any of the issued tokens (RN-5008)

    • an invalid combination with the JWT secret (RN-5008)

    • when the subject or user of the token does not exist in WHATS'ON

    • when the user does not have permissions to log into the API because of the access type or a missing API endpoint

  • Expired token: when the token has expired.

  • Revoked token: when the token has been revoked (RN-5008)

Note that existing tokens will not work anymore after the upgrade as the verification now expects the JWT standard.

Issued tokens on user account

WHATS'ON now keeps track of the issued tokens for a user in the Issued tokens tab on the user account. Note that not the actual token is not stored on the database. Tokens can also be revoked from this tab. See RN-5008 for more information.

API endpoint on REST services and user accounts

WHATS'ON REST APIs can be protected from unauthorized access by enabling authentication on the service settings. When used, access to API resources require a bearer access token header, as part of each request. This token is obtained by authenticating to a logon endpoint, using a user and password of a WHATS'ON password with access type API or UI and API. (RN-1917)

Up until now, an API user could be used to access any WHATS'ON REST API.

In order to provide better control of which user can access which services, an additional level of API permissions has been added.

On the service configuration, the drop-down API endpoint is available where it can be used to specify the endpoint needed for this service. It is only enabled when the Authentication is set to User-based JWT.

On the user account, the drop-down Allowed API endpoints is available, where it can be used to specify which endpoints the user has access to. It is only enabled when the Access type is set to API or UI and API.

The field takes its values from the new drop-down list MgXAPIEndPoint. The user code for each value is mandatory since it will be used for authentication.

When a user authenticates to a REST API service by sending a login call, the token is returned. When it is decoded, the aud claim will contain the user codes of the API endpoints of the user. In my example, the user has the endpoints BAPI and Push defined.

When the user sends a call with the token to the API, the API endpoints of the service and user are compared. If the service has no end points defined, those of the user do not need to be checked. If it does, it will be checked if the API endpoint of the service matches any of the endpoints on the user account. If not, a 403 response is returned:

{
  "statusCode": "403",
  "message": "The account being accessed does not have sufficient permissions to execute this operation. 
              User not allowed for this API endpoint.",
  "timestamp": "2022-08-19T13:50:49Z"
}

If user has the endpoint, the call is handled and executed.

2022r4

Applications part of business API module

Previously, certain applications that are needed for using the business APIs were not part of the business API module. This meant that when the module was not active, it was still possible to access them.

From this version, the following applications can only be used when the business API module is active:

  • Business API browser

  • File API log entry browser

  • the Business API interface and the File BAPI interface service types when creating a new service

Fix for BAPI service receiving tokens

When using the business API service to send calls to WHATS'ON, it is possible to authenticate using a user-based JWT.

Previously, when a token was sent with a POST /login call to the service, for example via Postman, the system crashed. This was because of a bug in the token parser.

This issue has been fixed.

2021r1.001

Previously, the messages returned by the REST interfaces (configurable REST with REST API definitions or the BAPIs) had a different format depending on the type of error.

From this version, the format of the different messages has been made consistent per status code across XML and JSON REST responses.

2021r1.000

Maximum number of failed authentications for REST services

Previously, when logging into a REST service but the credentials could not be validated several times, it was not possible to configure notifications for this. However, invalid logins could be a sign that someone is trying to hack their way into the system and pose a security risk.

Therefore, in this version, a new property has been added to the REST services called Maximum number of failed authentications.

When a user of access type API fails to log in more than the number of times set in this field, and email notifications are configured, an email will be sent to the email addressee to notify that maximum authentication tries was exceeded.

The log of the service will then include a reference to the user and the IP address from which the logging in was attempted. This allows security officers to block this IP in the firewall.